Summary

We can create automated HTML reports by using RMarkdown. These reports are highly customisable and interactive. They can be viewed on any device with a browser. These reports present an opportunity to engage everyday people, staff, and decision makers with data through story telling.


Introduction

You’ve probably noticed we don’t write on clay tablets anymore. That’s not to say there aren’t advantages to that medium (longevity being one of them), but fundamentally we don’t use clay tablets because it was easier to transfer written information using paper. Nowadays, we are increasingly turning from paper documents to digital documents for similar reasons.

One big advantage of digital documents over clay tablets and paper is that the information within such documents can be updated easily. Despite advances in technology, many (if not most), organisations are not taking advantage of the opportunity to create living, automated reports. Such reports have the potential to bridge the gap between the people undertaking the analyses and the decision makers by combining a short written narrative with interactive graphics.

We can, today, make such reports using RMarkdown (like the one you’re reading one right now) These reports are highly customisable, and can also be rendered in PDF or WORD formats. The downside of such formats is that they are static and not interactive. However, we can maximise interactivity by rendering these documents in an HTML format. HTML can be read on any device with a browser. Not only that but they can also be inserted directly into websites. In the following sections I demonstrate some of the features of an HTML RMarkdown document created in program R.


Graphic elements

It is easy to include static images, interactive plots or tables in the report. Widgets (e.g. a download button) can also be attached to allow certain content to be downloaded by the reader. Given that graphic elements can often overwhelm the look of a report we also can organise graphic elements behind tabs:


Static

Interactive tables with widgets


Interactive graph

Hover or click over top right of graph to activate menu


Demonstrable code

One of the great advantages of report making in RMarkdown is that the analysis is actually embedded in the document. If you are undertaking a technical report you may want to show the underlying code and its output (such as the dinosaur animation below). Given that many users may be disinterested in the code this can be hidden from ordinary view but activated when required by clicking the code button:


library(datasauRus)
library(ggplot2)
library(gganimate)

ggplot(datasaurus_dozen, aes(x=x, y=y))+
  geom_point(size = 4, alpha = 0.5, colour = "#149414")+
  theme_void() +
  transition_states(dataset, 3, 1) + 
  ease_aes('cubic-in-out')

Embedding results

One important part of scientific reporting is the integration of outputs into text. For example, we may have worked out the averaged weights of penguins (and their standard deviation) but want to present this as text rather in a table. The advantage with embedding these results using code is that we don’t have to constantly rewrite the passage if the data changes (as it will change automatically), it also eliminates the possibility of typographical mistakes.

library(palmerpenguins)
library(tidyverse)

peng <- na.omit(penguins) %>%
  group_by(species) %>% 
  summarise(average.weight = round(mean(body_mass_g),-1),
            sd = round(sd(body_mass_g),-1))

# RMarkdown code:

# *"Gentoo penguins are the heaviest of the **`r nrow(peng)`** species with an average weight of **`r  prettyNum(peng[which(peng$species == "Gentoo"),"average.weight"], big.mark=",", preserve.width="none")`** $\pm$ **`r  peng[which(peng$species == "Gentoo"),"sd"]` g **compared to an average weight of **`r  prettyNum(peng[which(peng$species == "Adelie"),"average.weight"], big.mark=",", preserve.width="none")`**$\pm$ **`r  peng[which(peng$species == "Adelie"),"sd"]` g** for Adelie penguins and **`r  prettyNum(peng[which(peng$species == "Chinstrap"),"average.weight"], big.mark=",", preserve.width="none")`** $\pm$ **`r  peng[which(peng$species == "Chinstrap"),"sd"]` g** for Chinstrap penguins."*


By using R code embedded in the RMarkdown text we can automate the values (shown in bold):


“Gentoo penguins are the heaviest of the 3 species with an average weight of 5,090 \(\pm\) 500 g compared to an average weight of 3,710 \(\pm\) 460 g for Adelie penguins and 3,730 \(\pm\) 380 g for Chinstrap penguins.”


Typesetting equations

If you are preparing a technical document for a scientific audience you have to include some mathematical equations. Typically, these equations are manually typeset and prone to human error. But thanks to the R package equatiomatic standard mathematical equations can be generated directly from your analysis. Below is a mathematical equation for determining the sex of penguins using an approach called logistic regression:


library(equatiomatic)

pr <- glm(sex ~ species + bill_length_mm, 
          data = penguins, 
          family = binomial(link = "logit"))

extract_eq(pr, wrap = TRUE, terms_per_line = 2)

\[ \begin{aligned} \log\left[ \frac { P( \operatorname{sex} = \operatorname{male} ) }{ 1 - P( \operatorname{sex} = \operatorname{male} ) } \right] &= \alpha + \beta_{1}(\operatorname{species}_{\operatorname{Chinstrap}})\ + \\ &\quad \beta_{2}(\operatorname{species}_{\operatorname{Gentoo}}) + \beta_{3}(\operatorname{bill\_length\_mm}) \end{aligned} \]


Conclusion

RMarkdown is an easy way to automate the production of shareable, interactive reports. At the same time because the reports are written in code they are easily reproducible. Furthermore, as these reports can be structure to allow access to code and the parent data sources they can facilitate institutional transparency.